home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / u_man / cat3 / Tk / crterrhdlr.z / crterrhdlr
Text File  |  1998-10-30  |  12KB  |  199 lines
  1.  
  2.  
  3.  
  4. TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr((((3333TTTTkkkk))))                          TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr((((3333TTTTkkkk))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      Tk_CreateErrorHandler, Tk_DeleteErrorHandler - handle X protocol errors
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ttttkkkk....hhhh>>>>
  13.  
  14.      Tk_ErrorHandler
  15.      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr(_d_i_s_p_l_a_y, _e_r_r_o_r, _r_e_q_u_e_s_t, _m_i_n_o_r, _p_r_o_c, _c_l_i_e_n_t_D_a_t_a)
  16.  
  17.      TTTTkkkk____DDDDeeeelllleeeetttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr(_h_a_n_d_l_e_r)
  18.  
  19. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  20.      Display           *_d_i_s_p_l_a_y     (in)      Display whose errors are to be
  21.                                               handled.
  22.  
  23.      int               _e_r_r_o_r        (in)      Match only error events with
  24.                                               this value in the _e_r_r_o_r__c_o_d_e
  25.                                               field.  If -1, then match any
  26.                                               _e_r_r_o_r__c_o_d_e value.
  27.  
  28.      int               _r_e_q_u_e_s_t      (in)      Match only error events with
  29.                                               this value in the _r_e_q_u_e_s_t__c_o_d_e
  30.                                               field.  If -1, then match any
  31.                                               _r_e_q_u_e_s_t__c_o_d_e value.
  32.  
  33.      int               _m_i_n_o_r        (in)      Match only error events with
  34.                                               this value in the _m_i_n_o_r__c_o_d_e
  35.                                               field.  If -1, then match any
  36.                                               _m_i_n_o_r__c_o_d_e value.
  37.  
  38.      Tk_ErrorProc      *_p_r_o_c        (in)      Procedure to invoke whenever an
  39.                                               error event is received for
  40.                                               _d_i_s_p_l_a_y and matches _e_r_r_o_r,
  41.                                               _r_e_q_u_e_s_t, and _m_i_n_o_r.  NULL means
  42.                                               ignore any matching errors.
  43.  
  44.      ClientData        _c_l_i_e_n_t_D_a_t_a   (in)      Arbitrary one-word value to pass
  45.                                               to _p_r_o_c.
  46.  
  47.      Tk_ErrorHandler   _h_a_n_d_l_e_r      (in)      Token for error handler to
  48.                                               delete (return value from a
  49.                                               previous call to
  50.                                               TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr).
  51.  
  52.  
  53. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  54.      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr arranges for a particular procedure (_p_r_o_c) to be
  55.      called whenever certain protocol errors occur on a particular display
  56.      (_d_i_s_p_l_a_y).  Protocol errors occur when the X protocol is used
  57.      incorrectly, such as attempting to map a window that doesn't exist.  See
  58.      the Xlib documentation for XXXXSSSSeeeettttEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr for more information on the
  59.      kinds of errors that can occur.  For _p_r_o_c to be invoked to handle a
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr((((3333TTTTkkkk))))                          TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr((((3333TTTTkkkk))))
  71.  
  72.  
  73.  
  74.      particular error, five things must occur:
  75.  
  76.      [1]  The error must pertain to _d_i_s_p_l_a_y.
  77.  
  78.      [2]  Either the _e_r_r_o_r argument to TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr must have been
  79.           -1, or the _e_r_r_o_r argument must match the _e_r_r_o_r__c_o_d_e field from the
  80.           error event.
  81.  
  82.      [3]  Either the _r_e_q_u_e_s_t argument to TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr must have been
  83.           -1, or the _r_e_q_u_e_s_t argument must match the _r_e_q_u_e_s_t__c_o_d_e field from
  84.           the error event.
  85.  
  86.      [4]  Either the _m_i_n_o_r argument to TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr must have been
  87.           -1, or the _m_i_n_o_r argument must match the _m_i_n_o_r__c_o_d_e field from the
  88.           error event.
  89.  
  90.      [5]  The protocol request to which the error pertains must have been made
  91.           when the handler was active (see below for more information).
  92.  
  93.      _P_r_o_c should have arguments and result that match the following type:
  94.           typedef int Tk_ErrorProc(
  95.                ClientData _c_l_i_e_n_t_D_a_t_a,
  96.                XErrorEvent *_e_r_r_E_v_e_n_t_P_t_r);
  97.      The _c_l_i_e_n_t_D_a_t_a parameter to _p_r_o_c is a copy of the _c_l_i_e_n_t_D_a_t_a argument
  98.      given to TTTTccccllll____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr when the callback was created.
  99.      Typically, _c_l_i_e_n_t_D_a_t_a points to a data structure containing application-
  100.      specific information that is needed to deal with the error.  _E_r_r_E_v_e_n_t_P_t_r
  101.      is a pointer to the X error event.  The procedure _p_r_o_c should return an
  102.      integer value.  If it returns 0 it means that _p_r_o_c handled the error
  103.      completely and there is no need to take any other action for the error.
  104.      If it returns non-zero it means _p_r_o_c was unable to handle the error.
  105.  
  106.      If a value of NULL is specified for _p_r_o_c, all matching errors will be
  107.      ignored:  this will produce the same result as if a procedure had been
  108.      specified that always returns 0.
  109.  
  110.      If more than more than one handler matches a particular error, then they
  111.      are invoked in turn.  The handlers will be invoked in reverse order of
  112.      creation:  most recently declared handler first.  If any handler returns
  113.      0, then subsequent (older) handlers will not be invoked.  If no handler
  114.      returns 0, then Tk invokes X'es default error handler, which prints an
  115.      error message and aborts the program.  If you wish to have a default
  116.      handler that deals with errors that no other handler can deal with, then
  117.      declare it first.
  118.  
  119.      The X documentation states that ``the error handler should not call any
  120.      functions (directly or indirectly) on the display that will generate
  121.      protocol requests or that will look for input events.''  This restriction
  122.      applies to handlers declared by TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr; disobey it at your
  123.      own risk.
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr((((3333TTTTkkkk))))                          TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr((((3333TTTTkkkk))))
  137.  
  138.  
  139.  
  140.      TTTTkkkk____DDDDeeeelllleeeetttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr may be called to delete a previously-created error
  141.      handler.  The _h_a_n_d_l_e_r argument identifies the error handler, and should
  142.      be a value returned by a previous call to TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEEvvvveeeennnnttttHHHHaaaannnnddddlllleeeerrrr.
  143.  
  144.      A particular error handler applies to errors resulting from protocol
  145.      requests generated between the call to TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr and the call
  146.      to TTTTkkkk____DDDDeeeelllleeeetttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr.  However, the actual callback to _p_r_o_c may not
  147.      occur until after the TTTTkkkk____DDDDeeeelllleeeetttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr call, due to buffering in the
  148.      client and server.  If an error event pertains to a protocol request made
  149.      just before calling TTTTkkkk____DDDDeeeelllleeeetttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr, then the error event may not
  150.      have been processed before the TTTTkkkk____DDDDeeeelllleeeetttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr call.  When this
  151.      situation arises, Tk will save information about the handler and invoke
  152.      the handler's _p_r_o_c later when the error event finally arrives.  If an
  153.      application wishes to delete an error handler and know for certain that
  154.      all relevant errors have been processed, it should first call
  155.      TTTTkkkk____DDDDeeeelllleeeetttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr and then call XXXXSSSSyyyynnnncccc;  this will flush out any
  156.      buffered requests and errors, but will result in a performance penalty
  157.      because it requires communication to and from the X server.  After the
  158.      XXXXSSSSyyyynnnncccc call Tk is guaranteed not to call any error handlers deleted before
  159.      the XXXXSSSSyyyynnnncccc call.
  160.  
  161.      For the Tk error handling mechanism to work properly, it is essential
  162.      that application code never calls XXXXSSSSeeeettttEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr directly; applications
  163.      should use only TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr.
  164.  
  165.  
  166. KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
  167.      callback, error, event, handler
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.